<document title="MenuGen">
<define name="version" value="">
<define name="date" value="" length=30 align="right">




<literal mode="Text">
=============================================================================
MenuGen - Create Menus for RISC OS Applications                  Version $$version$$

(c) Stephen Fryatt, 2001-2020                  $$date$$
=============================================================================
</literal>



<chapter title="Licence" file="Licence">

<cite>MenuGen</cite> is licensed under the EUPL, Version&nbsp;1.2 only (the "Licence"); you may not use this work except in compliance with the Licence.

You may obtain a copy of the Licence at <link ref="#url http://joinup.ec.europa.eu/software/page/eupl">http://joinup.ec.europa.eu/software/page/eupl</link>

Unless required by applicable law or agreed to in writing, software distributed under the Licence is distributed on an &quot;<strong>as is</strong>&quot; basis, <strong>without warranties or conditions of any kind</strong>, either express or implied.

See the Licence for the specific language governing permissions and limitations under the Licence.

The source for <cite>MenuGen</cite> can be found alongside this binary download, at <link ref="#url http://www.stevefryatt.org.uk/software">http://www.stevefryatt.org.uk/software</link>

</chapter>




<chapter title="Introduction" file="Introduction">

<cite>MenuGen</cite> provides a means of building RISC&nbsp;OS menus into a form of &quot;Template File&quot; which can be loaded into an application's workspace and passed directly to <code>Wimp_CreateMenu</code>. Items such as indirected data buffers are handled automatically.

</chapter>




<chapter title="Using MenuGen" file="Use">

To use <cite>MenuGen</cite>, a menu definition file must be created in a text editor and passed as a parameter to the <command>menugen</command> command.

<comdef target="menugen" params="&lt;source&gt; &lt;output&gt; [-d] [-m] [-v]">

The <command>menugen</command> command takes two parameters:

<list>
<li><command>source</command> is the filename of the text file containing the menu definitions.
<li><command>output</command> is the filename to which the binary Menus file is to be written.
</list>

Three option flags can also be specified:

<list>
<li><command>-d</command> indicates that dialogue box name tags are to be embedded into the file.
<li><command>-m</command> indicates that menu name tags are to be embedded into the file.
<li><command>-v</command> specifies verbose output, where details of the file parsing and data structures will be printed to screen.
</list>
</comdef>

Included with <cite>MenuGen</cite> is a stand-alone <cite>MenuTest</cite> utility, which will parse a binary Menus file generated by <cite>MenuGen</cite> and print details about it to stdout.

<comdef target="menutest" params="&lt;file&gt;">

The <command>menutest</command> command takes one parameter:

<list>
<li><command>file</command> is the filename of the binary menu file to be parsed and decoded.
</list>
</comdef>


</chapter>




<chapter title="Menu Definition Files" file="DefFiles">

Menu definition files consist of a text file containing a series of commands. The syntax is C-like, so that commands are terminated with semi-colons and nested with braces ('{' and '}').  Comments can be included in the files by enclosing them within <code>/*</code> and <code>*/</code>.

Files are case sensitive, and commands are always in lower case.

The top-level of a file consists of one or more <command>menu</command> commands, each followed by a nested block containing its definition.  An example might look as follows:

<codeblock>
/* Example Menu Definition File
 * -- for use with MenuGen 2
 */

menu(iconbar_menu, "My App")
{
  item("Info") {
    d_box(prog_info) {
      warning;
    }
    dotted;
  }
  item("Help") {
    submenu(help_menu);
  }
  item("Choices...") {
    dotted;
  }
  item("Quit");
}

menu(help_menu, "Help")
{
  item("Use interactive help") {
    ticked;
    dotted;
  }
  item("View manual");
  item("Visit website");
}
</codeblock>



<subhead title="Top-level commands">

A file consists of one or more top-level commands which define the menu structures.

<comdef target="menu" params="(tag, &quot;title&quot;)">

The <command>menu</command> command defines a new, empty menu.  It takes two parameters:

<list>
<li><command>tag</command> is a alphanumeric tag, which will be used to identify the menu within <cite>MenuGen</cite> and, if embedded into the file, by the application. It can not contain spaces.
<li><command>title</command> is the menu title. If longer than 12 characters, it will automatically become indirected.
</list>

The <command>menu</command> command can be followed by a block, containing the menu definition; if it is not, a default menu containing a single empty item will be created.
</comdef>

<subhead title="Menu commands">

The <command>menu</command> command can be followed by a block, containing one or more of the following commands to define the menu.  If it is not, or if any commands are omitted, defaults are used which conform to the <cite>Style Guide</cite>; a menu really needs at least one <command>item</command>, otherwise it will be of little use.

Multiple <command>item</command> commands can be used to add menu items in sequence; if more than one of any other command is encountered, the last one will take effect.

<comdef target="colours" params="(title_fg, title_bg, work_fg, work_bg)">

In the context of a <command>menu</command> command, the <command>colours</command> command sets the colours of the menu in terms of the standard Wimp colours 0 to 16. Its parameters are:

<list>
<li><command>title_fg</command> is the title foreground colour.
<li><command>title_bg</command> is the title background colour.
<li><command>work_fg</command> is the work area foreground colour.
<li><command>work_bg</command> is the work area background colour.
</list>

If omitted, the standard defaults of (7, 2, 7, 0) are used.
</comdef>

<comdef target="indirected" params="(length)">

In the context of a <command>menu</command> command, the <command>indirected</command> command sets the title to be indirected with the specified space reserved. If the title given in the <command>menu</command> command itself was longer than 12 characters it will already be indirected, but the command can still be used to set the amount of space reserved.

<list>
<li><command>length</command> specifies the number of characters to allocate, not including the string terminator.
</list>

If omitted, titles of 12 characters or less will be non-indirected and those that are longer will only have buffers of the original length allocated.
</comdef>

<comdef target="item" params="(&quot;text&quot;)">

The <command>item</command> command defines a new menu item: each <command>menu</command> command can contain one or more, which will be taken in the order they appear.  It takes one parameter:

<list>
<li><command>text</command> is the menu item text. If longer than 12 characters, it will automatically become indirected.
</list>

The <command>item</command> command can optionally be followed by a block containing more details; if it is not, a default text entry is created which conforms to the <cite>Style Guide</cite>.
</comdef>


<comdef target="item_gap" params="(gap)">

The <command>item_gap</command> command sets the space between menu items, in OS units.

<list>
<li><command>gap</command> specifies the space between menu items, in OS units.
</list>

If omitted, the gap is a standard 0 units.
</comdef>


<comdef target="item_height" params="(height)">

The <command>item_height</command> command sets the height of the menu items, in OS units.

<list>
<li><command>height</command> specifies the item height, in OS units.
</list>

If omitted, the height is a standard 44 units.
</comdef>


<comdef target="reverse">

The <command>reverse</command> command sets the menu to appear reversed (opening right to left).

It is not implemented in this version of MenuGen, and menus always open left to right.
</comdef>


<subhead title="Item commands">

The <command>item</command> command can be followed by a block, containing one or more of the following commands to define the menu item.  If it is not, or if any commands are omitted, defaults are used which conform to the <cite>Style Guide</cite> and result in a standard menu entry.

If more than one instance of any command is encountered in an <command>item</command> command, the last one will take effect.

<comdef target="colours" params="(icon_fg, icon_bg)">

In the context of an <command>item</command> command, the <command>colours</command> command sets the colours of the menu in terms of the standard Wimp colours 0 to 16. Its parameters are:

<list>
<li><command>icon_fg</command> is the icon foreground colour.
<li><command>icon_bg</command> is the icon background colour.
</list>

If omitted, the default values of (7, 0) are used.
</comdef>

<comdef target="d_box" params="(tag)">

The <command>d_box</command> command specifies that the menu item leads to a dialogue box. When the Menus file is loaded into an application, it will be necessary to specify window handles for each box: either by tag, or in an order specified by <cite>MenuGen</cite> on file compilation (depending on the compilation options specified).

If required, the command can be followed by a group to specify further options for the dialogue.

<list>
<li><command>tag</command> gives an alphanumeric tag to identify the dialogue box by. It can not contain spaces.
</list>
</comdef>

<comdef target="dotted">

The <command>dotted</command> command specifies that the menu item will be followed by a dotted line.
</comdef>


<comdef target="indirected" params="(length)">

In the context of an <command>item</command> command, the <command>indirected</command> command sets the item text to be indirected with the specified space reserved. If the text given in the <command>item</command> command itself was longer than 12 characters it will already be indirected, but the command can still be used to set the amount of space reserved.

<list>
<li><command>length</command> specifies the number of characters to allocate, not including the string terminator.
</list>

If omitted, item texts of 12 characters or less will be non-indirected and those that are longer will only have buffers of the original length allocated.
</comdef>


<comdef target="shaded">

The <command>shaded</command> command indicates that the menu item will be shaded.
</comdef>

<comdef target="sprite">

The <command>sprite</command> command indicates that the menu item will contain a sprite instead of text, and can be followed by a group defining further features of the sprite.

The <command>sprite</command> command is not implemented, and all menu items must be text.
</comdef>

<comdef target="submenu" params="(tag)">

The <command>submenu</command> command indicates that the menu item leads to a submenu, defined elsewhere in the file by another <command>menu</command> command and identified by its tag.

If required, the command can be followed by a group to specify further options for the submenu.

<list>
<li><command>tag</command> gives the tag of the menu to be linked as a submenu.
</list>
</comdef>

<comdef target="ticked">

The <command>ticked</command> command indicates that the menu item should be ticked by default.
</comdef>

<comdef target="writable">

The <command>writable</command> command indicates that the menu item should be writeable. If not specified as indirected with the <command>indirected</command> command, then item will be made indirected and given a length of 12 characters plus terminator.

If required, the command can be followed by a group to specify a validation string.
</comdef>


<subhead title="Dialogue box and submenu commands">

The <command>d_box</command> and <command>submenu</command> commands can optionally be followed by a group containing additional options for the menu item concerned.

<comdef target="always">

The <command>always</command> command sets the item to always be traversable, even when shaded.
</comdef>

<comdef target="warning">

The <command>warning</command> command sets the item to return a Message_SubmenuWarning.
</comdef>


<subhead title="Sprite commands">

The <command>sprite</command> command can optionally be followed by a group containing additional options affecting the sprite.

<comdef target="half">

The <command>half</command> command sets the sprite to appear at half size.

The <command>half</command> and <command>sprite</command> commands are not implemented, and all menu items must be text.
</comdef>


<subhead title="Writable commands">

The <command>writable</command> command can optionally be followed by a group containing additional options for the entry.

<comdef target="validation" params="(&quot;string&quot;)">

The <command>validation</command> command sets a validation string for the writeable menu entry.

<list>
<li><command>string</command> sets the validation string.
</list>

If omitted, the writeable entry will have no validation string applied.
</comdef>

</chapter>




<chapter title="Menu Block Files" file="MenuFiles">

The Menu Block files created by <cite>MakeMenus</cite> are binary data files containing snapshots of the menu block data, indirection data and validation strings, along with enough other information to be able to link everything together once it is loaded into memory. The intention is that an application will use OS_File 255 or an equivalent to load the data into memory, and then use it in-situ.

Whenever pointers are included to identify other parts of the file, they are given as offsets from the start of the file.  An offset of -1 is taken to indicate &quot;no pointer&quot; or &quot;end of list&quot;.


<subhead title="File header">

The file starts with a 12-byte header, as follows:

<codeblock>
0: Offset to dialogue list (or -1 for none)
4: Offset to indirected data list (or -1 for none)
8: Offset to validation data list (or -1 for none)
</codeblock>

There may optionally be an extended header, consisting of another 16 bytes, following immediately:

<codeblock>
12: Zero word to identify the extended header.
16: Option flag word (currently unused, and set to 0)
20: Offset to menu tag list (or -1 for none)
24: Zero word to identify the end of the header.
</codeblock>

Since without an extended header, byte 12 would be the offset to the next menu definition (and hence -1 if there was only one menu in the file), the presence of zero at this location is used to identify a file in the new format. Since the offsets will never be zero, a zero word at the end of the header is used to delimit the extent of the block.

Each of the lists above is described in its own section below.

<subhead title="Menu data">

Starting immediately after the header blocks (so at offset 12 or 28, depending on whether an extended header is present) are a sequence of menu data blocks.  Each consists of the following data:

<codeblock>
+0: Offset to the next menu data block (or -1 for the last block)
+4: Offset to the first item in the submenu list (or -1 for none)
+8: Start of Wimp_CreateMenu structure (ie. menu title data)
</codeblock>

The next menu block offset points to the start of the Wimp_CreateMenu block for that menu: that is, it points to the 8th byte of the data block.

The submenu list links in any menu items which use this menu block as a submenu.  The offset points to the first submenu pointer (bytes 4-7 of the menu item block); each submenu pointer then contains an offset to the next pointer or -1 if they are the last in the list (which must be read before being replaced by the real pointer).


<subhead title="Menu tag list">

If the file contains an extended header and the word at offset 20 is not -1, then there is a list of embedded menu tags which can be used to locate menu definitions. In this case, the word at offset 20 points to a sequence of tag blocks:

<codeblock>
+0: Offset to menu definition (or -1 for end of list)
+4: Tag name (zero terminated)
</codeblock>

Each block is rounded up to the nearest multiple of four bytes.  The offsets point to the start of the Wimp_CreateMenu structure (ie. the menu title data) for the menu whose tag is included in the block.


<subhead title="Dialogue list">

If first word of the file is not -1, there is a list of dialogue box pointers that needs to be filled in. This can take two formats, depending on whether dialogue box tags were embedded in the file when it was compiled.  These lists take the same form as the submenu lists attached to the menus.

If tags were not embedded (the original format), all the dialogue box pointers are in a single chain and the first word points to the first submenu pointer (bytes 4-7 of the menu item block) in the file.  Each pointer in turn contains an offset to the next pointer, or -1 if it is the last in the list.  The order that the pointers appear in the list is indicated when the file is compiled by <cite>MenuGen</cite>, and the application must know this in order to be able to correctly restore them.

If tags were embedded (the new format), then word 0 of the file points to the start of a dialogue box tag block:

<codeblock>
+0: Zero word to identify the new format
+4: Start of dialogue tag data
</codeblock>

The first word of the data will always be zero, and since this can never be in the old format chain of offsets it identifies the new format.  From byte 4 of the data onwards, there are a sequence of tag blocks:

<codeblock>
+0: Offset to first item in dialogue list (or -1 for end of list)
+4: Tag name (zero terminated)
</codeblock>

Each block is rounded up to the nearest multiple of four bytes.  The offsets point to shorter dialogue lists (in the same format as above) which contain only those items which use the dialogue whose tag is included in the block.


<subhead title="Indirected data">

If the second word of the file is not -1, it is an offset to the indirected data.  Similar to the new-format dialogue list, this is a sequence of word-aligned blocks as follows:

<codeblock>
+0: Offset to the 12 bytes of title or icon data (or -1 for end of list)
+4: Indirection data block
</codeblock>

The application must traverse this list, locating the indirection pointer in bytes 0-3 of the title or icon data and writing the real address of the indirection block to it.  The buffer length given in bytes 8-11 of the data can then be added to the 4 bytes used for the data pointer and rounded up to a multiple of 4 to identify the length of the indirected data block.

The end of the indirected data is indicated by a block containing an offset of -1 and no data block.


<subhead title="Validation data">

If the third word of the file is not -1, it is an offset to the validation data.  Similar to the indirected data (described above) this is a sequence of word-aligned blocks as follows:

<codeblock>
+0: Offset to the 12 bytes of icon data (or -1 for end of list)
+4: Length of validation block (including 8-byte header)
+8: Validation data block
</codeblock>

The application must traverse this list, locating the validation pointer in bytes 4-7 of the icon data and writing the real address of the validation block to it.  Unlike the indirected blocks, the block length given in the second word of the block already includes the necessary word rounding, and can be used to step to the next block.

The end of the validation data is indicated by a block containing an offset of -1 and no data block.

</chapter>



<chapter title="Version History" file="History">

Here is a list of the versions of <cite>MenuGen</cite>, along with all the changes made.


<subhead title="1.00 (17 February 2001)">

Original BBC BASIC code.


<subhead title="2.00 (17 September 2012)">

Rewritten in C for use with GCCSDK.


</chapter>





<literal mode="Text">


Updates and Contacting Me
-------------------------

  If you have any comments about MenuGen, or would like to report any bugs
  that you find, you can email me at the address below.

  Updates to MenuGen and more software for RISC OS computers can be found
  on my website at http://www.stevefryatt.org.uk/software/

  Stephen Fryatt
  email: info@stevefryatt.org.uk
</literal>
